﻿<html dir="LTR" xmlns:ndoc="urn:ndoc-schema">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="history" name="save" />
    <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5" />
    <title>Clock Class</title>
    <xml>
    </xml>
    <link rel="stylesheet" type="text/css" href="MSDN.css" />
  </head>
  <body id="bodyID" class="dtBODY">
    <div id="nsbanner">
      <div id="bannerrow1">
        <table class="bannerparthead" cellspacing="0">
          <tr id="hdr">
            <td class="runninghead">A MIDI Library for .NET</td>
            <td class="product">
            </td>
          </tr>
        </table>
      </div>
      <div id="TitleRow">
        <h1 class="dtH1">Clock Class</h1>
      </div>
    </div>
    <div id="nstext">
      <p> A clock for scheduling MIDI messages in a rate-adjustable, pausable timeline. </p>
      <p>
								For a list of all members of this type, see <a href="Midi~Midi.Clock~Members.html">Clock Members
								</a>.
							</p>
      <p>
        <a href="http://msdn.microsoft.com/en-us/library/System.Object(VS.90).aspx">System.Object</a>
        <br />   <b>Clock</b></p>
      <div class="syntax">
        <div>public class Clock</div>
      </div>
      <H4 class="dtH4">Thread Safety</H4>
      <P>This type is safe for multithreaded operations.</P>
      <h4 class="dtH4">Remarks</h4>
      <p>Clock is used for scheduling MIDI messages. Though you can always send messages synchronously with the various <a href="Midi~Midi.OutputDevice.html">OutputDevice</a>.Send* methods, doing so requires your code to be "ready" at the precise moment each message needs to be sent. In most cases, and especially in interactive programs, it's more convenient to describe messages that <i xmlns="urn:ndoc-schema">will</i> be sent at specified points in the future, and then rely on a scheduler to make it happen. Clock is such a scheduler.</p>
      <h3 xmlns="urn:ndoc-schema">Basic usage</h3>
      <p> In the simplest case, Clock can be used to schedule a sequence of messages which is known in its entirety ahead of time. For example, this code snippet schedules two notes to play one after the other:</p>
      <pre class="code">Clock clock(120);  // beatsPerMinute=120
OutputDevice outputDevice = ...;
clock.Schedule(new NoteOnMessage(outputDevice, Channel.Channel1, Note.E4, 80, 0));
clock.Schedule(new NoteOffMessage(outputDevice, Channel.Channel1, Note.E4, 80, 1));
clock.Schedule(new NoteOnMessage(outputDevice, Channel.Channel1, Note.D4, 80, 1));
clock.Schedule(new NoteOffMessage(outputDevice, Channel.Channel1, Note.D4, 80, 2));
</pre>
      <p>At this point, four messages have been scheduled, but they haven't been sent because the clock has not started. We can start the clock with <a href="Midi~Midi.Clock.Start.html">Start</a>, pause it with <a href="Midi~Midi.Clock.Stop.html">Stop</a>, and reset it with <a href="Midi~Midi.Clock.Reset.html">Reset</a>. We can change the beats-per-minute at any time, even as the sequence is playing. And the playing happens in a background thread, so your client code can focus on arranging the notes and controlling the clock.</p>
      <p>You can even schedule new notes as the clock is playing. Generally you should schedule messages for times in the future; scheduling a message with a time in the past simply causes it to play immediately, which is probably not what you wanted.</p>
      <h3 xmlns="urn:ndoc-schema">NoteOnOffMessage and Self-Propagating Messages</h3>
      <p>In the above example, we wanted to play two notes but had to schedule four messages. This case is so common that we provide a convenience class, <a href="Midi~Midi.NoteOnOffMessage.html">NoteOnOffMessage</a>, which encapsulates a Note On message and its corresponding Note Off message in a single unit. We could rewrite the above example as follows:</p>
      <pre class="code">Clock clock(120);  // beatsPerMinute=120
OutputDevice outputDevice = ...;
clock.Schedule(new NoteOnOffMessage(outputDevice, Channel.Channel1, Note.E4, 80, 0, 1));
clock.Schedule(new NoteOnOffMessage(outputDevice, Channel.Channel1, Note.D4, 80, 1, 1));
</pre>
      <p>This works because each NoteOnOffMessage, when it is actually sent, does two things: it sends the Note On message to the output device, and <i xmlns="urn:ndoc-schema">also</i> schedules the correponding Note Off message for the appropriate time in the future. This is an example of a <i xmlns="urn:ndoc-schema">self-propagating message</i>: a message which, when triggered, schedules additional events for the future.</p>
      <p>You can design your own self-propagating messages by subclassing from <a href="Midi~Midi.Message.html">Message</a>. For example, you could make a self-propagating MetronomeMessage which keeps a steady beat by always scheduling the <i xmlns="urn:ndoc-schema">next</i> MetronomeMessage when it plays the current beat. However, subclassing can be tedious, and it is usually preferable to use <a href="Midi~Midi.CallbackMessage.html">CallbackMessage</a> to call-out to your own code instead.</p>
      <h4 class="dtH4">Requirements</h4>
      <p>
        <b>Namespace: </b>
        <a href="~Midi.html">Midi</a>
      </p>
      <p>
        <b>Assembly: </b>Midi (in Midi.dll)
					</p>
      <h4 class="dtH4">See Also</h4>
      <p>
        <a href="Midi~Midi.Clock~Members.html">Clock Members</a> | <a href="~Midi.html">Midi Namespace</a></p>
      <hr />
      <div id="footer">
        <p>
          <a>Copyright © 2009 Tom Lokovic</a>
        </p>
        <p>Generated from assembly Midi [1.1.0.0] by <a href="http://ndoc3.sourceforget.net">NDoc3</a></p>
      </div>
    </div>
  </body>
</html>